//=============================================================================
// System  : MatchKit
// File    : IMatchBag.cs
// Author  : Fabio Bussu  (matchkit@fabiobussu.it)
// Updated : 04/16/2013
// Note    : Copyright 2013, Fabio Bussu, All rights reserved
//
// This code is published under the Microsoft Public License (Ms-PL). A copy
// of the license should be distributed with the code.  It can also be found
// at the project website: http://matchkit.codeplex.com. This notice, the
// author's name, and all copyright notices must remain intact in all
// applications, documentation, and source files.
//
// Version     Date     Who  Comments
// ============================================================================
// 1.0.0.0  04/16/2013   FB  First draft
//=============================================================================
using System;
#if EX
using System.Linq.Expressions;
#endif
using System.Reflection;

namespace MatchKit.ObjectMapping
{
	/// <summary>
	/// Provides a container to collects successful matches of an object mapping process.
	/// </summary>
	/// <remarks>
	/// MatchKit library provides a defalt implementation with <see cref="T:MatchBag"/>.
	/// </remarks>
	/// <conceptualLink target="7e345cd8-5aaa-4616-a3c9-abcd0544dabc" />
	/// <conceptualLink target="0a06b2a9-5f58-409a-ba62-639cfd77bca7" />
	public interface IMatchBag
	{
		/// <summary>
		/// Clears the content of the bag.
		/// </summary>
		void Clear();

		/// <summary>
		/// Regsters a successfully mapped member.
		/// </summary>
		/// <param name="instance">The mapped instance. This value cannot be null.</param>
		/// <param name="member">The mapped member. This value cannot be null.</param>
		/// <param name="match">The reslted match. This value cannot be null.</param>
		void Trace(object instance, MemberInfo member, Match match);

		/// <summary>
		/// Retrieves a match object given a mapped instance and a mapped member.
		/// </summary>
		/// <param name="instance">The mapped instance. This value cannot be null.</param>
		/// <param name="member">The mapped member. This value cannot be null.</param>
		Match GetMatch(object instance, MemberInfo member);

		/// <summary>
		/// Retrieves a match object given a mapped instance and a member name.
		/// </summary>
		/// <param name="instance">The mapped instance. This value cannot be null.</param>
		/// <param name="memberName">The mapped member name. This value cannot be null.</param>
		Match GetMatch(object instance, string memberName);

		#if EX
		/// <summary>
		/// Retrieves a match object given a mapped instance and an expression member reference.
		/// </summary>
		/// <param name="instance">The mapped instance. This value cannot be null.</param>
		/// <param name="memberReference">The mapped member name. This value cannot be null.</param>
		Match GetMatch<TInstance, TMember>(TInstance instance, Expression<Func<TInstance, TMember>> memberReference);
		#endif
	}
}
